From 4e3ec883263f6cc6c3e42fdd66f67747434d9594 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 18 Oct 2001 22:08:33 +0000 Subject: [PATCH] Resurrect 1.2 documentation. (#62604) * gdk/tmpl/visuals.sgml: Resurrect 1.2 documentation. (#62604) * gtk/tmpl/gtkpaned.sgml: Fixes. (#62146) * gtk/tmpl/gtkgamma.sgml: Fixes. (#62155) * gtk/Makefile.am (IGNORE_HFILES): Add xembed.h (#61929) --- docs/reference/ChangeLog | 8 ++ docs/reference/gdk/gdk-sections.txt | 2 +- docs/reference/gdk/tmpl/visuals.sgml | 161 +++++++++++++++++++------- docs/reference/gtk/Makefile.am | 3 +- docs/reference/gtk/tmpl/gtkgamma.sgml | 8 +- docs/reference/gtk/tmpl/gtkpaned.sgml | 4 +- 6 files changed, 133 insertions(+), 53 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index c0566641a4..fd1f698abf 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,13 @@ 2001-10-18 Matthias Clasen + * gdk/tmpl/visuals.sgml: Resurrect 1.2 documentation. (#62604) + + * gtk/tmpl/gtkpaned.sgml: Fixes. (#62146) + + * gtk/tmpl/gtkgamma.sgml: Fixes. (#62155) + + * gtk/Makefile.am (IGNORE_HFILES): Add xembed.h (#61929) + * gdk-pixbuf/gdk-pixbuf.types: Add GdkPixbuf, GdkPixbufAnimation and GdkPixbufAnimationIter. (#62590) diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt index f3e44cccb2..7077f63cbc 100644 --- a/docs/reference/gdk/gdk-sections.txt +++ b/docs/reference/gdk/gdk-sections.txt @@ -439,7 +439,6 @@ GDK_TYPE_SUBWINDOW_MODE Visuals visuals GdkVisual -GdkVisualClass GdkVisualType GdkByteOrder gdk_query_depths @@ -462,6 +461,7 @@ GDK_TYPE_VISUAL_TYPE GDK_TYPE_VISUAL GDK_IS_VISUAL GDK_IS_VISUAL_CLASS +GdkVisualClass GDK_VISUAL GDK_VISUAL_CLASS GDK_VISUAL_GET_CLASS diff --git a/docs/reference/gdk/tmpl/visuals.sgml b/docs/reference/gdk/tmpl/visuals.sgml index 25f1a2789c..559c015821 100644 --- a/docs/reference/gdk/tmpl/visuals.sgml +++ b/docs/reference/gdk/tmpl/visuals.sgml @@ -7,13 +7,15 @@ Low-level display hardware information -A #GdkVisual describes a particular video hardware display format. For example, -a piece of display hardware might support 24-bit color, 16-bit color, or 8-bit -color; meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can be in -different formats; for example the "red" element of an RGB pixel may be in the -top 8 bits of the pixel, or may be in the lower 4 bits. +A #GdkVisual describes a particular video hardware display format. It includes +information about the number of bits used for each color, the way the bits are +translated into an RGB value for display, and the way the bits are stored in +memory. For example, a piece of display hardware might support 24-bit color, +16-bit color, or 8-bit color; meaning 24/16/8-bit pixel sizes. For a given +pixel size, pixels can be in different formats; for example the "red" element +of an RGB pixel may be in the top 8 bits of the pixel, or may be in the lower +4 bits. - Usually you can avoid thinking about visuals in GTK+. Visuals are useful to interpret the contents of a #GdkImage, but you should avoid #GdkImage precisely @@ -22,65 +24,134 @@ all but the most low-level purposes. Also, anytime you provide a #GdkColormap, the visual is implied as part of the colormap (gdk_colormap_get_visual()), so you won't have to provide a visual in addition. + +There are several standard visuals. The visual returned +by gdk_visual_get_system() is the system's default +visual. gdk_rgb_get_visual() return the visual most +suited to displaying full-color image data. If you +use the calls in #GdkRGB, you should create your windows +using this visual (and the colormap returned by +gdk_rgb_get_colormap()). + + +A number of functions are provided for determining +the "best" available visual. For the purposes of +making this determination, higher bit depths are +considered better, and for visuals of the same +bit depth, %GDK_VISUAL_PSEUDO_COLOR is preferred at +8bpp, otherwise, the visual types are ranked in the +order of (highest to lowest) %GDK_VISUAL_DIRECT_COLOR, +%GDK_VISUAL_TRUE_COLOR, %GDK_VISUAL_PSEUDO_COLOR, +%GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE, +then %GDK_VISUAL_STATIC_GRAY. + -#GdkImage, #GdkColormap +#GdkImage, #GdkColormap, #GdkRGB -Description of an image data format +The GdkVisual structure contains information about +a particular visual. -@parent_instance: inherited portion from #GObject -@type: -@depth: -@byte_order: -@colormap_size: -@bits_per_rgb: -@red_mask: -@red_shift: -@red_prec: -@green_mask: -@green_shift: -@green_prec: -@blue_mask: -@blue_shift: -@blue_prec: +
+Constructing a pixel value from components + +guint +pixel_from_rgb (GdkVisual *visual, + guchar r, guchar b, guchar g) +{ + return ((r >> (16 - visual->red_prec)) << visual->red_shift) | + ((g >> (16 - visual->green_prec)) << visual->green_shift) | + ((r >> (16 - visual->blue_prec)) << visual->blue_shift); +} + +
- - - - +@parent_instance: inherited portion from #GObject +@type: The type of this visual. +@depth: The number of bits per pixel. +@byte_order: The byte-order for this visual. +@colormap_size: The number of entries in the colormap, for + visuals of type %GDK_VISUAL_PSEUDO_COLOR or + %GDK_VISUAL_GRAY_SCALE. For other visual types, it + is the number of possible levels per color component. + If the visual has different numbers of levels for + different components, the value of this field is undefined. +@bits_per_rgb: The number of significant bits per red, green, or blue + when specifying colors for this visual. (For instance, for + gdk_colormap_alloc_color()) +@red_mask: A mask giving the bits in a pixel value that + correspond to the red field. Significant only for + %GDK_VISUAL_PSEUDOCOLOR and %GDK_VISUAL_DIRECTCOLOR. +@red_shift: The red_shift and + red_prec give an alternate presentation + of the information in red_mask. + red_mask is a contiguous sequence + of red_prec bits starting at bit + number red_shift. For example, + shows constructing a pixel value + out of three 16 bit color values. +@red_prec: See above. +@green_mask: A mask giving the bits in a pixel value that + correspond to the green field. +@green_shift: The green_shift and + green_prec give an alternate presentation + of the information in green_mask. +@green_prec: See above. +@blue_mask: A mask giving the bits in a pixel value that + correspond to the blue field. +@blue_shift: The blue_shift and + blue_prec give an alternate presentation + of the information in blue_mask. +@blue_prec: See above. - - - -@GDK_VISUAL_STATIC_GRAY: -@GDK_VISUAL_GRAYSCALE: -@GDK_VISUAL_STATIC_COLOR: -@GDK_VISUAL_PSEUDO_COLOR: -@GDK_VISUAL_TRUE_COLOR: -@GDK_VISUAL_DIRECT_COLOR: +A set of values that describe the manner in which the +pixel values for a visual are converted into RGB +values for display. + + +@GDK_VISUAL_STATIC_GRAY: Each pixel value indexes a grayscale value directly. +@GDK_VISUAL_GRAYSCALE: Each pixel is an index into a color map that maps pixel + values into grayscale values. The color map can be changed by an application. +@GDK_VISUAL_STATIC_COLOR: Each pixel value is an index into a predefined, + unmodifiable color map that maps pixel values into RGB values. +@GDK_VISUAL_PSEUDO_COLOR: Each pixel is an index into a color map that maps + pixel values into rgb values. The color map can be changed by an application. +@GDK_VISUAL_TRUE_COLOR: Each pixel value directly contains red, green, + and blue components. The red_mask, + green_mask, and + blue_mask fields of the #GdkVisual + structure describe how the components are assembled into a pixel value. +@GDK_VISUAL_DIRECT_COLOR: Each pixel value contains red, green, and blue + components as for %GDK_TRUE_COLOR, but the components are mapped via a + color table into the final output table instead of being converted directly. - +A set of values describing the possible byte-orders +for storing pixel values in memory. -@GDK_LSB_FIRST: -@GDK_MSB_FIRST: +@GDK_LSB_FIRST: The values are stored with the least-significant byte + first. For instance, the 32-bit value 0xffeecc would be stored + in memory as 0xcc, 0xee, 0xff, 0x00. +@GDK_MSB_FIRST: The values are stored with the most-significant byte +first. For instance, the 32-bit value 0xffeecc would be stored +in memory as 0x00, 0xcc, 0xee, 0xff. -@depths: +@depths: @count: @@ -90,7 +161,7 @@ Description of an image data format @visual_types: -@count: +@count: @@ -98,7 +169,7 @@ Description of an image data format -@Returns: +@Returns: @@ -106,7 +177,7 @@ Description of an image data format -@Returns: +@Returns: @@ -122,7 +193,7 @@ Description of an image data format -@Returns: +@Returns: @@ -130,7 +201,7 @@ Description of an image data format -@Returns: +@Returns: diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 35ce033b1d..4da3b662d5 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -45,7 +45,8 @@ IGNORE_HFILES= \ gtktextsegment.h \ gtktexttagprivate.h \ gtktexttypes.h \ - gtktypebuiltins.h + gtktypebuiltins.h \ + xembed.h # Images to copy into HTML directory HTML_IMAGES = diff --git a/docs/reference/gtk/tmpl/gtkgamma.sgml b/docs/reference/gtk/tmpl/gtkgamma.sgml index a3326cee5f..897426c1ed 100644 --- a/docs/reference/gtk/tmpl/gtkgamma.sgml +++ b/docs/reference/gtk/tmpl/gtkgamma.sgml @@ -15,13 +15,13 @@ a subclass of #GtkCurve for editing gamma curves. distribution. -The #GtkGammaCurve widget is a subclass of #GtkCurve specifically for +The #GtkGammaCurve widget is a variant of #GtkCurve specifically for editing gamma curves, which are used in graphics applications such as the Gimp. -The #GammaCurve widget shows a curve which the user can edit with the mouse -just like a #GtkCurve widget. On the right of the curve it also displays +The #GtkGammaCurve widget shows a curve which the user can edit with the +mouse just like a #GtkCurve widget. On the right of the curve it also displays 5 buttons, 3 of which change between the 3 curve modes (spline, linear and free), and the other 2 set the curve to a particular gamma value, or reset it to a straight line. @@ -34,7 +34,7 @@ to a straight line. -The #GtkGammaCurve-struct struct contains private data only, and +The #GtkGammaCurve struct contains private data only, and should be accessed using the functions below. diff --git a/docs/reference/gtk/tmpl/gtkpaned.sgml b/docs/reference/gtk/tmpl/gtkpaned.sgml index f3f8f1df49..d8f63101cb 100644 --- a/docs/reference/gtk/tmpl/gtkpaned.sgml +++ b/docs/reference/gtk/tmpl/gtkpaned.sgml @@ -79,7 +79,7 @@ Add a child to the top or left pane with default parameters. This is equivalent to -gtk_paned_pack1(paned, FALSE, TRUE); +gtk_paned_pack1(paned, child, FALSE, TRUE); @@ -92,7 +92,7 @@ gtk_paned_pack1(paned, FALSE, TRUE); Add a child to the bottom or right pane with default parameters. This is equivalent to -gtk_paned_pack1(paned, FALSE, FALSE); +gtk_paned_pack2(paned, child, TRUE, TRUE); -- 2.30.2